SPACE 1/SPACE - Library 1 - Volume 1.iso/program/356/context2/context.doc

Text File | 1990-02-02 | 24KB | 577 lines

===========================================================================

          ***************       ConTEXT v2        ****************

                           A Programming Editor

                   (C) Don Milne and MicroPack Ltd 1986

===========================================================================

Here at last (yet again) the long promised version two of my programming
editor. I finally decided to call it ConTEXT (as opposed to Context,
ConText or CONTEXT). I originally used that name partly because that seems
a nice name for an editor, and partly because it was the name I had thought
up for a context-sensitive editor that I never got around to writing (I
went off the context-sensitive idea before I had written a line).

When I released version one of this program I said in the docs that I was
reasonably sure that there was no serious bugs in it. Boy was I wrong! The
basis of my original confidence was that I was using the program myself
every day and had found no bugs, but I had not appreciated just how much
some peoples working practices differed from mine - and some of those
different but quite valid practices turned up bugs that I had not.

My grateful thanks goes to Ron Sprunger who put in a great deal of his time
and provided me with two detailed lists of bugs, misfeatures and
improvement suggestions. These were invaluable to me in preparing ConTEXT
v2. My thanks also to Jim Fox for uploading the code to BIX at a time when
I did not myself have the necessary software (well, I had CrossTalk (on a
PC) which supports Xmodem, but Xmodem is just too slow and expensive for
uploading from the UK).

I had hoped to provide multiple editing windows in this version of ConTEXT,
but that will take a certain amount of work to achieve, and I simply cannot
afford the time at the moment (not unless ConTEXT becomes a paying concern
at any rate). So, rather than withhold the program until every last feature
is added I have decided to get it out *now* and start getting feedback
*now*. Do let me know what you think of my work either on BIX (my BIX-ID is
"mpack"), or by phone or mail (see below for the address).

ConTEXT is distributed on a shareware basis - it is not public domain. I
like the shareware concept because I am a programmer who does not believe
in copy protection, or in charging rip-off prices for a piece of code.
However I *do* believe that a programmer should be payed a fair price for
his work, and I have put a great deal of work into this. If you use this
program and feel that it is worth something then I would be grateful if you
could send me whatever you think it is worth (I think that around $40 is
about right - or 40 pounds if you live in the UK). Remember that the amount
of time I devote to this program in future will depend greatly on how much
you make it worth my while - I have to eat you know!

As an incentive, users who register register will receive a copy of the
latest version of the editor, and will be informed when later versions are
available, and will be able to get those updates for the price of a disk
and the return postage. The Modula-2 program source will also be available
to registered users for a further payment of $50 (or 50 pounds in the UK),
you can order it when you register if you like.

Our address is in the 'About ConTEXT' box in the editor. Payment is by
bankers draft, or by cheque drawn on a UK bank made payable to 'MicroPack
Ltd'. We can also accept payment by VISA or American Express, if you want
to do so then please drop me a line (on BIX, or by phone or mail), giving
me the card number, the expiry date, and the name of the card holder.

---------------------------------------------------------------------------

ConTEXT's sole reason for existance is that TDI's editor was so bad,
I was prepared to write my own rather than use theirs. 1st Word is a
good editor in many ways (and still is for real word processing), but
as a programming editor just couldn't hack it (I'm spoiled - I can't work
without autoindent by default, plus integration with the compiler). Note
that if you want to use this editor from the TDI Desktop, you should
rename CONTEXT.PRG as EDITOR.PRG (that's what the Desktop looks for when
you invoke the editor).

ConTEXT can be operated using the standard GEM mouse and menu interface, or
entirely from the keyboard. The keyboard commands are totally configurable,
and comes ready configured with commands which are almost all WordStar (tm)
compatable - users of the Turbo Pascal (tm) editor will also find these
commands familiar. ConTEXT also makes use of some of the special purpose
keys on the Atari ST keyboard.

As a consequence of various tricks being used to speed up Screen IO,
ConTEXT does not interact all that well with some Desk Accessories, one
unfortunate example being the M2 Options Accessory. This is one bug that
has remained from the original version of the editor, mainly because it is
not much of a problem - in fact the only accessory I have found which gives
problems is TDI's one, so now I just don't use it within ConTEXT.

ConTEXT requires an Atari 520 or 1040 ST, Monochrome or Medium Res Color.

Don Milne.
MicroPack Ltd.

------------------------------------------------------------------------

The Files on the Disk
=====================

These are the files which you recieve with ConTEXT:-


CONTEXT.PRG            - ConTEXT, the program itself.

CONTEXT2.RSC           - the resource file for ConTEXT, usable in mono or
                         medium res. This must be in the current directory
                         when ConTEXT is run.

CCONTEXT.PRG           - Configure ConTEXT. Use this program to change the
                         keyboard commands to some you like better. Also
                         used to load the compiler error messages, and the
                         "built-in" macros.

CONTEXT.CFG            - ConTEXT's configuration file, produced by
                         CCONTEXT. This must be in the current directory
                         when ConTEXT is run.


ERRORS.TXT             - A list of errors reported by the compiler. This
                         file is required by CCONTEXT.

MACROS.TXT             - A list of macros to be bound in to the editor as
                         if they were normal, built-in commands. This file
                         is used by CCONTEXT but is not required.

CONTEXT.DOC            - This file.


------------------------------------------------------------------------


WordStar Command Summary
========================

The following sections describe the default, WordStar/Turbo-compatible
command set that I provide as the standard configuration with ConTEXT. If
you have reconfigured with your own prefered commands then this will not be
of much use to you, but then you ought to know what you did yourself!


CURSOR CONTROL
--------------

WordStar Cursor movement keys are intended to be mnemonic because of
the physical organisation of the keys on a standard keyboard, and not
because of the letters on the keys themselves.

Unlike the Turbo Pascal editor, all cursor movement commands wrap onto
next or previous lines. For example typing cursor-right when the cursor
is already at the right of a line causes the cursor to be moved to the
beginning of the next line. If your intention was actually to insert a
space at the end of the line you should use the space bar instead.

Also unlike the Turbo editor is the feature that lines deleted using
the "Delete Line" command (^Y or FKey10), are copied into the paste
buffer before deletion. The line can be restored by typing the UNDO
key. In fact several lines may be deleted at a time, (using consecutive
"Delete Line" commands), and all will be restored by typing the UNDO key AS
LONG AS YOU DO NOTHING WHICH AFFECTS THE PASTE BUFFER BEFOREHAND. The paste
buffer is affected by block operations, and by delete operations. Besides
adding a touch of protection against disasters, this feature is often used
in preference to a WordStar block command. Where just a few lines are
involved this method is usually more convenient.

Text removed using the Block Delete command is also copied into the paste
buffer and may be restored by typing UNDO.

The only major deviation from Turbo is that ConTEXT uses the "^Q-E"
sequence to mean "Find Error" (find a compiler-reported error). In
WordStar/Turbo, ^Q-E means "move to top-of-page". The opposite command
(^Q-X, "move to bottom-of-page"), is also removed to preserve symmetry.
Also note that ConTEXT interpretes the "Global" flag in replace
operations somewhat differently - In the Turbo editor setting "Global"
means "Replace all occurrences of the target", while ConTEXT interpretes it
as "Replace all occurrences of the target STARTING FROM THE CURRENT CURSOR
POSITION". To achieve the same results as the Turbo example you need to
jump to the top of the file before executing the replace.


Movement Commands
-----------------

Command Description           Keystroke(s)          ST Alternate

Line Up                          ^E                 Cursor Up
Line Down                        ^X                 Cursor Down
Character Left                   ^S                 Cursor Left  ( <-- )
Character Right                  ^D                 Cursor Right ( --> )
Word Left                        ^A
Word Right                       ^F
Scroll Up                        ^W
Scroll Down                      ^Z
Page Up                          ^R                 '-' key on keypad
Page Down                        ^C                 '+' key on keypad
Left on Text                                        '0' key on keypad
Left on Line                     ^Q-S
Right on Line                    ^Q-D               '.' key on keypad
Top of File                      ^Q-R               '*' key on keypad
End of File                      ^Q-C               'Enter' key on keypad
Start of Block                   ^Q-B
End of Block                     ^Q-K
Jump to Marked Position          ^K-J


Insert and Delete Commands
--------------------------

Command Description           Keystroke(s)          ST Alternate

Insert Mode On/Off               ^V                 Insert
Insert Line                      ^N
Delete Line                      ^Y                 FKey10
Undelete Lines                                      Undo
Delete to End of Line            ^Q-Y
Delete Character under Cursor    ^G                 Delete
Delete Character to Left         ^H                 BackSpace
Delete Word                      ^T^T or ^T-T
Insert Tab (size 1)              ^I                 Tab
Insert Tab (size 2)                                 ALT-TAB



Block Commands
--------------

Command Description           Keystroke(s)          ST Alternate

Mark Block Begin                 ^K-B               FKey7
Mark Block End                   ^K-K               FKey8
Mark Single Word                 ^K-T
Hide/Display Block               ^K-H
Copy Block                       ^K-C
Move Block                       ^K-V
Delete Block                     ^K-Y
Read Block from Disk             ^K-R
Write Block to Disk              ^K-W
Print Block                      ^K-P



Macro Commands
--------------

Command Description           Keystroke(s)          ST Alternate

Execute Macro                                       FKey2
Read Macro                                          FKey3
Record Macro                                        FKey4
Write Macro                                         FKey5



File Commands
-------------

List File on Printer             ^K-L
Save File and Resume Editing     ^K-S
Save to Named File               ^K-N
Save and Edit New File           ^K-D
Save File and Exit               ^K-X
Abandon File                     ^K-Q



Misc. Commands
--------------

Repeat last Find/Replace         ^L
Find                             ^Q-F
Replace                          ^Q-A
Find Compile Error               ^Q-E
Set Marker                       ^K-M
Adjust Indentation               ^K-I
Toggle Word Case                 ^T-U
Toggle Word Capitalisation       ^T-C
Toggle Auto-Indent               ^Q-I
Toggle WP Mode                   ^Q-W  (enables word wrap and paragraph
                                        reformat command)
Reformat Paragraph               ^B
Enter a repeat factor            <ESC>nn (entered before a command or
                                          character causes that command
                                          to be repeated nn times or that
                                          character to be inserted nn
                                          times).


Note that ^L repeats the last find, or the last replace, or the last find
error. A find error is done automatically by ConTEXT when an error file is
detected, so ^L may be used right away in those cases (up until a normal
find or replace operation has been carried out).

The "Repeat" field in Find/Replace dialog boxes is also an undercover
WordStar options field. In other words, as well as being able to enter
digits from 0-9 (specifying a repeat factor), it is also possible to enter
letters from the set "ABGNQUW" each of which correspond to a particular
search option. The meanings of these letters is as follows:-

 n ---------- A number, repeat the operation n times
 A ---------- Abort Operation (same as clicking on CANCEL), except that
              you still need to press return to confirm.
 B ---------- Search Backwards
 G ---------- Global, only applies to Replace. Repeat replace operation
              for all occurrences of the target string searching from
              the current cursor position.
 U ---------- Convert target and pattern to uppercase before
              comparing (ie ignore case differences).
 W ---------- Whole words only. Patterns match only if the candidate is
              delimited by non-alphanumeric characters.
 Q ---------- Set QUERY mode, ie ask user to confirm before completing
              each replace operation.


The "Set Marker" is used in conjunction with the "Jump to Marker" command
and allows you to quickly return quickly to any point in a file if you have
to leave it for some reason.


Notes on Mouse/Menu Operations
==============================

The functions provided in the menus are more or less the same as those
provided in the WordStar/Turbo Command Set. Additional features are

   1. The text cursor may be quickly moved to any position on the
      screen by pointing with the mouse and clicking once with the
      left mouse button.

   2. Blocks may be marked by pointing with the mouse to the first character
      of the block, then holding down the left mouse button while the
      mouse cursor is moved to the last character of the block. A box
      will be grown around the text to be marked. When the box encloses
      all of the desired text, the mouse button may be released. The
      marked block will be highlighted. Obviously, this method may only
      be used when the entire text is visible on the screen at once,
      otherwise one of the alternative methods (eg menu or WordStar
      command or function keys) must be used.



Processing of Compile Errors
============================

Errors are handled in the same way as the standard TDI editor. When a
file is selected for editing ConTEXT looks for a matching file ending
in ".ERM" (or ".ERD" if the file is a definition module). ConTEXT uses
information from this file to mark errors in the source file. The
marker used looks like this - '@'.


Macros and Macro Syntax
=======================

The best way to describe the macro syntax is by example, so here is a
simple macro:-

.macro R
REPEAT

UNTIL ;$


All macros (in written form that is), start with the header ".macro c"
where c can be any single character. This entire header (including the
character) is case dependant - ".MACRO" is not acceptable, and 'C' is not
the same as 'c' for the identifying character. The macro itself is then a
sequence of characters terminated by the character '$'.  It is also
possible to invoke functions from within a macro by enclosing a "function
number" in angle brackets - if we elaborate our example a little:-

.macro R
REPEAT

UNTIL ;
<1><6:4><1>$


"<1>" means "Execute function 1" (Function 1 is the Cursor-Up command, a
list of function numbers can be found in Appendix A, and is also displayed
in the CCONTEXT program. You don't need to know function numbers if you use
the "Record Macro" way of creating the macro). The second function looks a
little strange bacause it specifies a repeat factor - "<6:4>" means repeat
function 4 (cursor right), 6 times. Always remember that the repeat factor
is the first number, then a colon, then the function number. It is possible
to specify a repeat factor without specifying a function to execute, in
which case the repeat factor is reserved for the character following the
closing angle bracket, for example the sequence:-

                  <45:>*

Will write the '*' character 45 times. Finally, the angle bracket can be
used as an escape character to introduce a character that would otherwise
have special meaning to the macro syntax checker, for example the
sequence:-

                  <$

means "insert the character '$' in the text - do not treat this as the end
of the macro". Generally speaking any character may be placed after a left
angle bracket to be literally inserted into the text - the following
characters can ONLY be inserted in this way:-

           '<'    '$'     '|'

Note that when using the '<' escape to enter special characters that you do
not need to enter a closing bracket, in fact if you do you will find it
also inserted into the text!.

The last thing you may find useful to know about macro syntax is that you
can replace any occurrence of a carriage return with the character '|'.
This allows you to write your macros in a more compact form. If we take our
example for the last time we can write it thusly:-

     .macro R|REPEAT||UNTIL ;|<1><6:4><1>$

The file MACROS.TXT contains examples of several macros that you may find
useful, including one to strip out hard tabs from a text file, plus several
of use to Modula-2 programmers. The macros in this file get bound in to the
configuration file and seem to the ConTEXT user to be built in commands of
the editor - saves having to re-enter your favorite macros every time!

Macros can be created in three ways:-

     1. Write your macro in text form into the MACROS.TXT file and use the
        CCONTEXT program to bind it into the editor.
     2. Write your macro in text form then read it with the "Read Macro"
        command.
     3. Record a macro by invoking the "Record Macro" command, do whatever
        it is once, then invoke the "Record Macro" command again to
        complete the recording.

However you create your macro you need to remember the character you used
to identify it, because this is asked for when you invoke the "Execute
Macro" command, and when you invoke the "Write Macro" command. The "Write
Macro" command can be used to write *any* macro out in text form -
regardless of how it was created.



The CCONTEXT (Configure ConTEXT) Program
========================================

CCONTEXT should be simple enough to operate (in fact I hope that it is
self-explanetory), however this section will summarise its operation.

The CCONTEXT program is used to configure the keyboard commands, and also
to bind in macros and compiler error messages into the editor. When you run
the program the following menu is displayed:-


      1.  Edit Keyboard Commands

      2.  Edit Misc Details

      Q.  Quit



Option 1 - Edit Keyboard Commands
---------------------------------

Option one brings up a secondary menu consisting of a list of the editor
commands which you may configure, selectable by function number (the
function numbers shown are the same as those recognised by the macro
processor).

You may then pick a function that you want to configure by typing its
function number. You may provide more than one command sequence for any
function, but there must be no more than 120 sequences in total (this
allows for two sequences for each function, which should be plenty).

After you have picked the function that you want to configure, you are
given the opportunity to add, or remove a function. To add a function just
press 'a', then type the two characters that make up the command. If the
command is only one character then type <CR> for the second character.



Option 2 - Edit Misc Details
----------------------------

This option allows you to configure such details as:-

     a) The background color (black or white).

     b) The tab sizes (two tab commands are provided).

     c) The initial settings of various flags, ie Insert Mode, Auto-Indent
        On/Off, WP Mode.


Q - Quit
--------

Quits the CCONTEXT program and causes it to write out the new configuration
file. For this the ERRORS.TXT file must be in the current directory, and
you should have the MACROS.TXT file also in the current directory if you
want the macros therein to be bound into the configuration. MACROS.TXT is
simply a list of the macros you want bound in, specified using the same
macro syntax used by the Macro Processor which is part of the ConTEXT
editor. The only "extras" in MACROS.TXT is that you may add comments before
and after macros (but not within macros!). Any line starting with a ';' in
the first column is treated as a comment line and is ignored. You may also
have blank lines in your macro file - before and after a macro blank lines
have no significance, within a macro they certainly do!  See the supplied
MACROS.TXT file for an actual example.


APPENDIX A - Macro Processor Function Numbers
---------------------------------------------

   Function     Function
   Number       Description
   --------     -----------
      1         Cursor Up
      2         Cursor Down
      3         Cursor Left
      4         Cursor Right
      5         Backspace
      6         Page Up
      7         Page Down
      8         Word Move Left
      9         Word Move Right
     10         Scroll Up
     11         Scroll Down
     12         Start Of File
     13         End Of File
     14         Delete Char
     15         Delete Line
     16         Delete to EOL
     17         Delete Word
     18         Undelete Lines
     19         Insert Line
     20         Left on Line
     21         Left on Text
     22         Right on Text
     23         Mark Start of Block
     24         Mark End of Block
     25         Mark Single Word
     26         Find Start of Block
     27         Find End of Block
     28         Hide/Display Block
     29         Copy Block
     30         Move Block
     31         Delete Block
     32         Read Block
     33         Write Block
     34         Print Block
     35         Find
     36         Find and Replace
     37         Find Compile Error
     38         Find/Replace again
     39         Set Marker
     40         Jump to Marker
     41         Print File
     42         Save File
     43         Save File As...
     44         Save & Edit new File
     45         Save and Exit
     46         Abandon Changes
     47         Adjust Indent
     48         Switch Window
     49         Execute Macro
     50         Read Macro
     51         Record Macro
     52         Write Macro
     53         Tab
     54         Tab 2
     55         Toggle Word Case
     56         Toggle Capitalisation
     57         Toggle Insert Mode
     58         Toggle Auto-Indent
     59         Toggle WP Mode
     60         Reformat Paragraph